=========================================================
MCURVE INSTITUTIONAL TRADING BOT - SETUP & OPERATIONS
=========================================================

1. EXTRACT THIS FOLDER to your Desktop.
2. OPEN the "env.txt" file. 
3. ENTER your License Key and TradingView Webhook Secret.
4. RENAME "env.txt" to exactly ".env" (Make sure your computer doesn't hide the file).
5. DOUBLE-CLICK the correct App for your computer:
   - Mac Users: Double-click "Start MCurve (Mac).app"
   - Windows Users: Double-click "Start MCurve (Windows).bat"

(Note: Do NOT click the raw "MCurveBot-Mac" or "MCurveBot-Win.exe" files directly, as they require the Start App to load your configuration files properly).

=========================================================
⚠️ CRITICAL WARNING: CLOUDFLARE NETWORK CONNECTION ⚠️
=========================================================
Out of the box, the "Start MCurve" apps use a Temporary Cloudflare Guest Tunnel (e.g., https://random-words.trycloudflare.com). 

THIS IS FOR PAPER TRADING AND DEMO TESTING ONLY.

Temporary tunnels are public and occasionally drop connection. If your tunnel drops while you are in a live trade, the bot will NOT receive the signal to exit, which could result in severe financial loss.

For LIVE TRADING, you MUST configure a Permanent Cloudflare Tunnel.

HOW TO SET UP A PERMANENT TUNNEL (DIY GUIDE):
1. Buy a custom domain name (e.g., from Namecheap or GoDaddy).
2. Create a free Cloudflare.com account and add your domain.
3. Change your domain's DNS Nameservers to point to Cloudflare.
4. Download and install the "cloudflared" daemon to your computer.
5. Open Terminal/Command Prompt and run: cloudflared tunnel login
6. Create a new tunnel: cloudflared tunnel create mcurve-bot
7. Route the tunnel to your domain: cloudflared tunnel route dns mcurve-bot yourdomain.com
8. Run the tunnel pointing to the bot: cloudflared tunnel --url http://localhost:3000

Once your permanent tunnel is running, you graduate to the Enterprise apps. To start the bot moving forward, DOUBLE-CLICK "Start Enterprise (Mac).app" or "Start Enterprise (Windows).bat".

WANT US TO DO IT FOR YOU?
If you do not have the technical experience to configure DNS records and terminal daemons, the MCurve Engineering Team can remotely install a permanent, Zero-Trust Enterprise Cloudflare Tunnel on your machine. 
Visit the Command Center on our website to upgrade to the $599 Enterprise Setup package.

=========================================================
🛑 API THROTTLING & IP BANS (DON'T RESTART IN A TRADE!) 🛑
=========================================================
When the bot is in an active trade, it shifts into High-Frequency 
Latency Bypass Mode. It aggressively polls the broker every 
2.5 seconds to mathematically un-blind the Elastic Profit Guard 
from WebSocket lag. 

If you restart the bot while a trade is active, it performs a 
massive "Startup Sync" (downloading accounts, contracts, orders, 
and positions) and immediately slams right back into 2.5s 
High-Frequency Polling.

Doing this multiple times triggers the broker's DDOS & Rate-Limit 
protection (Cloudflare / TopstepX WAF). The broker will slap your 
IP address with a strict 1-hour to 4-hour API ban (429 Too Many Requests).

HOW TO AVOID AND FIX IT:
1. NEVER restart the bot constantly while in an active trade. 
   Let the bot do its job.
2. If you see terminal warnings saying "API Throttled; returning null...", 
   DO NOT PANIC. The bot is successfully blocking its own requests 
   for 15 seconds to dodge a ban. It will heal itself.
3. If you are hard-banned (it's been over an hour and the bot still 
   can't connect), you must stop the bot completely (Ctrl+C) and 
   wait 60 minutes for the broker's firewall to clear your IP address 
   before turning it back on.

=========================================================
TROUBLESHOOTING & COMMON ERRORS
=========================================================

1. ERROR: "Code 3: Authentication failed"
- Fix 1: Ensure you generated the API key from trade.topstepx.com (Settings -> API), NOT from your ProjectX dashboard.
- Fix 2: Ensure your PROJECTX_USERNAME in the .env file is your actual TopstepX platform username (e.g., your_topstep_username) and NOT your email address. TopstepX explicitly rejects email addresses.

2. TopstepX Website Disconnects: "Multiple sessions detected"
- Fix: This means your bot is working perfectly! Topstep only allows one live market data connection at a time. Because your bot successfully authenticated and is streaming live data in the background, your web browser was automatically logged out. To monitor your trades, leave the TopstepX website closed and use your Bot Dashboard (http://localhost:3000) instead!

3. SMART ACCOUNT AUTO-DETECTION & DASHBOARD SELECTION
- Feature Highlight: Never worry about finding your exact hidden database Account ID! The bot features an intelligent Smart Fallback Mechanism that automatically scans your Topstep profile. Even if you accidentally enter your ProjectX web profile ID instead of your trading ID in the .env file, the bot will seamlessly detect your active trading account and lock onto it.
- Managing Multiple Accounts: If you trade multiple accounts, the bot has you completely covered. Simply use the local Bot Dashboard (http://localhost:3000) to switch between your active accounts on the fly. The bot instantly routes your trades to the selected account, and your selection is permanently saved—even if you restart the bot, it remembers exactly which account you left off on!
